PT-4575: Per-pane content zoom — chords, opt-in, tab menu, Settings, editor - #2821

Stacked on #2803 (pt-4576-content-zoom-platform-core). Review only the commits above that branch. Stacked PRs get no automatic CI here; the full local battery (typecheck, lint, format:check, and the unit suites of root, platform-bible-react, platform-bible-utils and the Scripture editor extension) is green.
Battery on the combined branch: typecheck (core, erb, e2e, workspaces) 0 errors; lint 0 errors; format:check clean; vitest run src 270 files / 3994 passed / 1 skipped; Scripture editor extension 94 files / 1530 passed; platform-bible-react unit 70 files / 915 passed; platform-bible-utils 32 files / 611 passed; build:extensions and the platform-bible-react build (through typedoc) clean.
After #2803 squash-merges, this branch is rebased with git rebase --onto <new base> <old parent tip>.

Summary

This is the rest of the per-pane content-zoom epic (PT-4575), combining the five work items that followed the platform core in #2803. A user can now zoom one pane's content instead of scaling the whole app: Ctrl/⌘ + - 0 and Ctrl/⌘ plus the mouse wheel change the level of the pane under the pointer or caret, the Scripture editor zooms its text and its footnotes list independently, Zoom in / Zoom out / Reset zoom to default appear in the web-view tab menu and in the editor's own hamburger menu, Settings offers a percent stepper for the default level every pane starts at, and macOS gets an explicit View menu with the same three actions. Each pane remembers its level.

• PT-4577, chord ownership and the macOS View menu. Main stops swallowing Ctrl + - 0 in before-input-event, so the bootstrap from PT-4576: Platform core for per-pane content zoom #2803 receives them. platform.zoomIn / platform.zoomOut stay as commands with no default chord, and their step goes through adjustZoomFactor, fixing the float drift that rejected the twentieth step. On macOS the View menu is explicit, with ⌘= / ⌘- / ⌘0 plus hidden numpad duplicates replacing the native zoom roles. A renderer top-document keydown listener covers window chrome, where no iframe sees the key. The keyboard-shortcuts catalog is updated.
• PT-4580, the opt-in contract. ContentZoomRoot (platform-bible-react, @experimental) is a forwardRef div carrying data-platform-content-zoom-root; no area prop marks the view's main area, area="footnotes" names a second independently zoomable pane. CONTENT_ZOOM_ROOT_ATTRIBUTE is duplicated in the library on purpose and pinned equal to core's by a test. Author docs land in the Extension-Development-Guide and Component-Builder-Patterns, three ADR entries record the decisions, and the Paratext 9 inventory gains a "Pane Zoom (View > Zoom)" entry.
• PT-4578, the tab menu. A platform.tabZoom group (order 50, not extensible, isExperimental) binds the three owner-routed commands from PT-4576: Platform core for per-pane content zoom #2803 ahead of the window group. Simple mode gets a tab menu for the first time, holding only that group; the tab title reads the contributed menu in both modes and narrows it before conversion. A tab hosting no web view gets no zoom items. This fulfils PT-3171.
• PT-4579, the Settings default and layout. platform.webViewContentZoom renders as − · 100 % · + · reset through a new renderer-internal PercentStepper, writing through the existing validate → setSetting tail without the text box's debounce. "Zoom factor" becomes Interface scaling and "Zoom" becomes Tab content default zoom. General reads Interface language, Interface scaling, Tab content default zoom; a new Supporter settings group holds Request timeout and the re-registration reminder; Interface mode is hidden, because the profile popover carries that switch in both modes.
• PT-4581, the Scripture editor. The Scripture text is the main area and the footnotes list the footnotes area, with the footnote-editing popover following the text's level; toolbar, divider and panel padding stay outside every area, so they keep their size. Editable and read-only editors share the web-view type and remember levels under editor:<projectId>:<area>. The editor's hamburger menu carries the three zoom items in both modes. Two platform fixes the first marked view exposed ship here: a click keeps its area active even when it moves focus elsewhere, and a pane whose replacement content runs no bootstrap drops its stale area list.

Why review this

This is the epic's user-visible half. It removes a long-standing app-wide shortcut on purpose, adds the first UI Simple mode offers on a tab, changes the tab title component every tab renders, and is the first proof of the opt-in contract from #2803.

Decisions worth a look

• Chord ownership. The chrome listener accepts Shift only for the zoom-in keys, matching the bootstrap's rule; a parity test pins the two copies to each other. resolveContentZoomTarget returns nothing while a dialog is open and the chrome listener checks the same query, so dialogs stay out of scope on every input path, including the macOS accelerators. Enhanced Resources' private Ctrl chord handler becomes reachable again on Windows/Linux; removal is PT-4583.
• ContentZoomRoot placement. The marker is rendered after the props spread, so area is always the source of truth. In the editor it goes inside PortalContents, because react-reverse-portal clones its direct child with the portal's props; editorContainerRef is untouched, since a marker there would nest the footnotes marker.
• Simple mode reaches the tab menu only on Column 3. The Home and Scripture Editor columns use a headless tab bar, so the editor's own hamburger menu is what carries zoom in both modes.
• Menu items cannot carry isExperimental. The item schema rejects unknown properties, so the group carries it, as platform.tabWindow already does.
• Items stay inert on a view with no zoom area. The service treats such a request as a silent no-op, and the "has areas" signal fills asynchronously, so disabling on it would show disabled items that in fact work.
• The relabel goes through a new key. "Zoom factor" is a shipped, immutable string, so Interface scaling arrives as %settings_platform_zoomFactor_label_2% with a deprecation entry, per the Localization Guide.
• No optimistic readout in the stepper. The stored value round-trips through the extension host before the prop updates. The readout always shows the stored value; only the baseline for a rapid next press uses the last emitted factor, within a 1.5 s window and until the prop moves. Two earlier optimistic attempts each opened a stuck-or-flicker case.
• The click-gesture rule. A focusin naming a different area within 200 ms of a pointerdown is ignored, so selecting a footnote row does not hand the active area back to the text; a focus change with no pointer behind it still sets the area.
• Stale areas are dropped by bootstrap liveness, not by a "re-reported since this load" flag: the fresh bootstrap reports from DOMContentLoaded, before the iframe's load event, so clearing at load would race that report.
• Keyboard-chord e2e cases are written but gated. Playwright drives keys through CDP, which never reaches before-input-event, so an ungated test would go green while the product path stayed untested. Ctrl+wheel and the commands cover the same paths.
• Observer cost is below measurement. A throwaway probe under a typing burst saw zero or one mutation batch and a scan below performance.now() resolution, so nothing was filed and the probe was not kept.
• Known follow-ups: the Simple-mode Home column has no menu of any kind and keeps only the chords (a UX question); the footnotes pane does not yet take the project font size (PT-4189); the indicator anchors to the union of main-marked elements, so the badge may sit at the footnote popover's corner while it is open; the platform-bible-react dist/ bundle is not byte-stable across builds, so a rebuild shows unrelated churn; a Storybook page for the epic is an open epic-level question; the macOS runtime check belongs to PT-4585.

Testing

• Renderer and main: macOS menubar data (11), the chrome-key listener (19), the dialog-open query (3), keyboard-catalog location existence, overlay-store and dialog-shard cases, resolver gate cases, a float-drift regression, the percent stepper (19) with the setting component and the General/Supporter layout data, the tab-menu data, filterTabMenuToGroup, the tab title's zoom menu (11), and bootstrap plus service cases for the gesture rule and stale areas (100 across the two).
• Library: content-zoom-root.component.test.tsx (7), the unit project, and npm run build through typedoc, with a fresh build leaving the committed dist/ unchanged.
• Extension: a jsdom render test for both footnotes pane positions, a source-contract test pinning the two main markers and the untouched scroll container, and a JSON test for the new menu group and strings.
• E2E, headless, one spec per invocation: content-zoom.spec.ts 1 passed (independent wheel zoom over text and footnotes, fixed toolbar height, indicator text and data-area, command path, per-area reset via a real click, shared memory identity with the read-only editor, memory keys); content-zoom-default-level.spec.ts 1 passed (seeded 120 % default). The scripture-editor isolated subset: 8 passed, 2 skipped (the gated chord file), 2 failing on a first-run tour dialog that fails identically on the base branch under the same invocation.
• Review passes: every work item ran /review-paratext (four analyzer passes) and an OpenCodeReview delegate pass, and roborev per-commit reviews were triaged on every commit. No Critical finding is open.
• Manual checks pending: Settings order, the live stepper, both modes and Spanish; the Power editor tab, a dialog tab, a Simple Column-3 tab, the keyboard path; caret accuracy and popover anchoring at 150 %, the Simple-mode character-marker bar off 100 %, and the spinner, book-not-available and empty-chapter views inside the new wrapper.

Risk Level

Medium. It removes an app-wide shortcut, changes the tab title component every tab renders in both modes, relabels two visible settings, and touches two platform paths that every marked view will share.

AI-assisted — Claude Code (Fable 5.1 coordinating; Opus design, investigation and review passes; per-task Sonnet agents under TDD; Sonnet verification passes).

🤖 Generated with Claude Code

Review round 1 (2026-09-16)

Fifteen commits answer @lyonsil's review; the branch was also restacked onto #2803's rebased tip (1bdd333). Four "Decisions worth a look" bullets above are superseded here:

• The dialog gate is modal-only and applies only where a pane has to be guessed. isAnyDialogOpen became isModalOverlayOpen (a modal dialog or the command palette); a docked non-modal dialog such as About blocks nothing, and resolveContentZoomTarget gates only the no-id path, so in-iframe chords, the wheel, the tab menu and explicitly targeted calls are never blocked (65a95458fb8). The chrome listener keeps its own explicit modal check after the key filter, and consumes a chord only when something can zoom (17b1cf03c8c, b22d332035b).
• Tab-menu zoom items are shown disabled on a pane with no zoom area, read synchronously from the resolver when the menu opens, in both modes (1bc7c7e63c0). The remaining edge is a menu opened inside the ~1 s mount grace of a freshly opened pane, which can grey items that would work a moment later. This also fixes a latent gap: renderTabMenuItems previously ignored item.disabled for every contributed tab-menu item.
• The click-gesture rule is bounded by Tab. A primary click still protects its area against the view's own answering refocus for 200 ms, but a Tab keydown ends the gesture, so a deliberate focus move retargets zoom at once; a right- or middle-click sets the area active but arms nothing (898294115de, b379382b791). By design §2.5 decision 1, a chord follows the caret while the menu follows the last click or focus, so after clicking a footnote row the two can act on different areas until the next focus move; the ADR and the catalog say so now.
• The keyboard-chord e2e cases run. Both stated blockers were gone; the file is unskipped and the footnotes case moves keyboard focus onto a footnote row before pressing the chord (77b2e83f900, ce167766772). Both cases pass on the first attempt.

Also in this round: the chrome listener registers in the capture phase so the reference box's picker cannot swallow the chords (17b1cf03c8c); each web view type's contributed tab menu is read once per process, so an extension installed mid-session shows its tab items at the next window reload (85f5991f70c); the Settings stepper's buttons use aria-disabled so they keep focus and their tooltip at a bound (0f68f04159b, b22d332035b); the debounced settings handler is memoized (e67b4efe879); the macOS menubar test clears its shared mock so the numpad cases can fail (fb70d1c0cac); and the ADR, the Extension Development Guide, the platform.zoomIn/zoomOut summaries and one Spanish string are corrected (ca75d2fd47b, cfc626960d5).

Scope reduction (product decision 2026-09-16): PT-4578 asked for the Simple-mode tab menu on the editor and Home tabs too. The headless Column 1/2 tab bars keep pointer-events: none; the editor's hamburger menu is the Simple-mode entry point, and the tab menu is delivered on Column 3 alone. Recorded in adr-simple-mode-tab-menu-offers-zoom-only.

Not taken here, on purpose: interface scaling stays Settings-only with the two commands callable and shortcut-less (PO decision 8, PRD NN-5, PT-4577); the 10 % snap on platform.zoomIn/zoomOut is ticket-ordered; the per-notch rescan and forced layout during Ctrl+wheel, and the nested-marker selector, live on #2803's branch and are handled there; the mode-switch dialog-request leak is fixed on its own branch off main (dialog-request-survives-layout-load); the macOS menu-combiner shallow copy is proposed as a follow-up ticket.

Battery on the tip: typecheck (core, erb, e2e, workspaces) 0 errors; lint 0 errors; format:check clean; vitest over the renderer services, docking, settings, main and stories trees 135 files / 2451 passed; content-zoom-chords.spec.ts 2 passed headless.

This change is 

Round 2 (review by lyonsil, 2026-09-16)

Forty-two commits answer @lyonsil's second review (two passes, 25 inline findings plus two that could
not be attached to a line). The branch was restacked onto #2803's rebased base (ca92e777ccf), and
then, after #2803 squash-merged into main (99b58a037aa), restacked a second time onto main; it now
carries 102 commits above main.

Chords. The zoom chords are declared once, in CONTENT_ZOOM_CHORDS in content-zoom.model.ts,
and the window-chrome listener, the in-view bootstrap and the macOS View menu are all built from that
one table — the two hand-kept copies that made the next two bugs possible in two places at once are
gone. Shift is accepted for every zoom chord rather than for zoom-in alone, so Ctrl+0 resets on
AZERTY and Czech layouts, where 0 is a shifted key and reset had no other keyboard route. The reset
chord's Numpad0 entry now requires key: '0', so with NumLock off the keystroke is Ctrl+Insert
and reaches Copy instead of being swallowed. The macOS View menu's accelerator is ⌘= with a hidden
⇧⌘= duplicate (⌘+ and ⌘= are different native key equivalents; the catalogue claimed the wrong one),
and the accelerators are asserted as literals rather than read back out of the table they come from.

Settings stepper. The stepper writes through the debounced handler like every sibling control, on
a 150 ms wait rather than the typed controls' longer one, so a burst of presses is one cross-process
write and one fan-out instead of one per press. It steps with the platform's own adjustZoomFactor
rather than a fourth copy of the arithmetic, which let min, max, step, roundToStep and
clampToProps go; with the generality gone it is renamed PercentStepper → ZoomStepper. Buttons,
readout and reset gates all derive from the same baseline, so the reset button no longer refuses the
click that its own stale aria-disabled should have allowed, and a burst keeps its place when an
older press is confirmed mid-burst. The bound tooltips say why a press does nothing ("Already at the
largest zoom (300 %)", the mirror at 50 %, and the reset button's at-default wording), in English and
Spanish. Two failures the optimistic readout exposed are fixed with it: a change with no writer is now
an error rather than a silent success, and a failed settings write is logged rather than existing only
as component state.

The window-input gate. ConnectionLostOverlay, WorkspaceUpdatingOverlay and FirstRunOverlay
bypass the overlay store entirely, so the chord gate did not stand down behind them and a chord could
zoom — and persist — a pane the user could not see. They now register through one hook into a
renderer-level store of blocking surfaces, keyed by token; the registration is a layout effect,
because a passive one commits after paint and leaves one frame in which the scrim is up and the gate
still answers "unblocked". The predicate is renamed isModalOverlayOpen → isWindowInputBlocked,
since "modal overlay" is no longer what it means.

Tab menu. The contributed tab-menu cache is keyed by interface mode as well as web view type, so
the first mode-gated tab item to land will not inherit a cache that cannot see a mode switch.

macOS menubar. The combiner mutated the module-level template's submenu arrays, so the first build
that merged a contributed column permanently corrupted the template for the process. It now builds a
per-entry copy that copies the submenu array (not structuredClone, not a JSON round trip — the zoom
items carry click closures). The same entry point had a second defect: a contributed column whose
label matched replaced the platform submenu outright, so that menubar shipped with no zoom items, no
reload, no dev tools and no full-screen toggle; contributed items are now interleaved with the
platform's by order. This closes PT-4633 in full.

Ctrl+wheel cost, measured and fixed. The per-notch forced layout was recorded only on PT-4581,
which closes with this PR, so we captured it before merge. Chrome tracing over a 3 s synthetic
Ctrl+wheel burst at 100 notches/s over the Scripture editor's text found ~1.46 s of a 3.58 s gesture
spent on style and layout forced synchronously inside the wheel handler, with 80 tasks over 16.7 ms.
Controls settled the attribution: the same gesture without Ctrl left the main thread 0.9 % busy, and
150 % and 100 % were indistinguishable, so it was the zoom mechanism, not the editor and not the zoom
level. Two commits fix it. The badge's placement (its getBoundingClientRect and getComputedStyle
reads) moved to one requestAnimationFrame per frame; re-capturing then showed the write itself was
the other half, so the zoom write is coalesced per frame too, through the bound helper's existing step
count — no message shape changed. Headline numbers across the three captures at 150 %: forced style +
layout inside the wheel handler 1459 ms → 0 ms; mean wheel dispatch including everything nested in
it 9.37 ms → 0.35 ms (worst 33.1 → 18.3 ms); style/layout passes over the gesture 299 → 147;
scripting + style + layout 61.0 % → 57.3 % of the window. Stated plainly because it is not fixed:
frame drops are not. Long tasks rose, because the write and the style and layout it forces now land in
the same frame task, and under this load Chromium delivers roughly one wheel event per frame, so
per-frame coalescing has reached its floor. The neighbouring pinch path was measured rather than
assumed: 536 adjust calls in a brisk pinch cost about 0.06 ms each and collapse into the one recalc
their frame owes anyway, so it needs no coalescing of its own. All of these numbers go on PT-4581.

Docs. The platform.zoomIn/zoomOut summaries and TSDoc say "by 10 %, stepping from the nearest
10 %" and carry #2803's naming ruling (interface scaling / tab content default zoom); the ADR records
what giving up the app-wide chords costs a Windows or Linux user, and then corrects itself — Enhanced
Resources answers all three chords from its own handler, so Notes and the Text Collection, not
Resources, are the views where they are dead; the tab menu's comment and ADR entry say the zoom items
are gated by a snapshot read at open, not by a subscription; the editor's zoom-area comment says what
the area actually contains; and a one-test-per-file rule the project does not have is dropped from two
e2e headers.

The restack

git rebase --onto ca92e777ccf 1bdd333eb06, with rerere disabled on every invocation. Seven
conflicts, all in this PR's own files; the saved diffs and the per-conflict resolutions are recorded
in the review notes. The two that changed behaviour rather than prose: the localization relabel took
the base's key layout (%settings_platform_zoomFactor_label_2% = "Interface scaling", the old key
deprecated) and dropped our in-place rename of the same string, and the platform.zoomFactor TSDoc is
the union of both sides rather than either one.

Two judgement calls in the wheel-handler merge, for the base owner. #2803 rewrote the whole wheel
path (tick accumulator with a carried remainder, a pinch branch with physical-modifier evidence, a
line/page-mode branch) while this branch replaced the single act(...) that path ended in. The base's
block is kept verbatim and the coalescer re-applied on top of it, which meant deciding (a) that only
the tick path is coalesced — the pinch and line/page branches stay immediate, since a pinch already
arrives once per frame — and (b) that the base's seven per-notch assertions are re-expressed as one
coalesced write carrying the steps the notches add up to, rather than as N single writes. A
subsequent pass corrected two things in that merge: a burst that reverses direction inside one frame
is no longer netted (at a bound the clamp absorbs travel the area cannot take, so a net would hand it
back — each direction now gets its own write, landing where the same notches land one at a time), and
a line/page-mode event or a pinch hands over any notches pending in that frame before it acts.

The second restack, onto main after #2803 squash-merged (99b58a037aa), had one conflict: the
committed platform-bible-react bundles, resolved by taking main's side and then rebuilding the
whole bundle set (f4002416b48). It also surfaced one semantic breakage — main's new middle-click
dock-layout contract test reads the tab title through useInterfaceMode as well as
useIsPowerMode, and the unmocked hook reached the real useSetting, so the test needed the
interface-mode hook mocked too (5ae33da1a1c).

Known, deliberate, and open

• Hidden panes and the per-frame wheel coalescing (cross-view-sync rule, hidden case). A wheel
  burst's pending steps are applied by a requestAnimationFrame callback inside the web view. In a
  pane whose tab is inactive (rc-dock keeps it mounted but display: none) no frame fires, so the
  steps wait and land whole, in one write, when the pane next paints; nothing is dropped and nothing
  is applied out of order. A hidden pane cannot receive a wheel event in the first place, so the only
  way to reach this is a burst that ends as the tab is switched away. Stated in the in-view script's
  docblock and here.
• In-view chords are not gated by the full-screen covers, and no longer need to be.
  resolveContentZoomTarget answers a caller that names a pane whatever is on top; only the guessing
  path stands down, and the gate fix above covers the window-chrome listener. A live check of what
  that leaves — focus sitting inside a web view while a cover is up — found the one cover that did
  not hold: connection-lost and first-run are Radix modals and trap focus, but the "Updating project
  view" cover was a plain role="status" div, so the iframe kept the keyboard and a chord typed into
  a pane nobody could see still zoomed it and persisted the level. That cover is now the same Radix
  modal dialog the other two are: it takes focus onto itself when it appears, keeps Tab inside it,
  and hands focus back to whatever held it when the switch ends (7da5b9cfbdd). So all three
  covers trap focus, and no chord reaches a web view behind any of them. Pinned by three tests in
  overlay-workspace-updating.component.test.tsx — focus leaves the web view, focus comes back, and
  the app behind the cover is aria-hidden (the same containment proxy the connection-lost suite
  uses, since jsdom cannot drive real Tab containment).
• Pop-ups that portal out of a zoom area still render at 100 % — the Simple-mode character-marker
  bar's menu, the marker menu and the comment editor. Making the platform-bible-react pop-up
  primitives follow the ContentZoomRoot they came from is PT-4634 on PT-4584: Content zoom for the comment list and the Comments panel #2825, which sits directly
  above this PR; the two non-descendant cases get their one-line opt-in there. If this PR merges
  alone, those pop-ups stay at 100 % until PT-4584: Content zoom for the comment list and the Comments panel #2825 merges. The "Simple-mode character-marker bar off
  100 %" item in the manual-checks list above is therefore re-pointed at PT-4584: Content zoom for the comment list and the Comments panel #2825.
• PT-4641 filed (Dev Task under PT-2161, not started): both useMemo'd debounces in
  other-setting.component.tsx and project-setting.component.tsx are rebuilt on every render,
  because each builds its validator as a fresh inline arrow, so an armed timer fires later with a
  stale closure instead of being cancelled. "One write per burst" holds only while that prop's
  identity is stable. The root cause is in two files this PR does not touch.

Battery on the tip: typecheck (core, erb, e2e, workspaces) 0 errors; lint 0 errors; format:check
clean; build:types leaves papi.d.ts unchanged; 23 affected suites 541/541, and test:core 321
files / 5359 passed / 0 failed at the restacked tip; the content-zoom e2e specs pass headless.

Trailer note: thirteen of this round's commits carry a Co-Authored-By: Claude Opus 5 (1M context)
trailer alongside the coordinating session's own.